Storing Halftone Information in a Format Collection(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 3 - Page Formatting and Dialog Box Customization / Using Format Objects and Collection Items to Format Pages

Storing Halftone Information in a Format Collection
Your application can store halftone information for each page in a document in a format collection. QuickDraw GX stores the halftone structure for a format object as a collection item in the format collection. For an introduction to printing with halftones, see "Halftones and Format Collections," which begins on page 3-21.
Halftones are described by the gxHalftone structure definition:
struct gxHalftone{
   fixed          angle;
   fixed          frequency;
   gxDotType      method;
   gxTintType     tinting;
   gxColor        dotColor;
   gxColor        backgroundColor;
   gxColorSpace   tintSpace;
};
The angle parameter describes the direction of the halftone. The frequency parameter describes the size of the dot, in cells per inch. The method parameter describes the way in which the halftone cell is filled. The tinting parameter describes how the desired color is converted into a ratio of color dots and background dots. The dotColor and backgroundColor parameters are the colors of the dots used to form the halftone. And the tintSpace parameter describes the color space that the original color is converted to before the tint value is determined. For detailed information on the gxHalftone structure, see the view-related objects chapter of Inside Macintosh: GX Objects.
The gxFormatHalftoneTag enumerator is used to identify the gxFormatHalftoneInfo structure in the format collection:
enum { gxFormatHalftoneTag = 'half' };

struct gxFormatHalftoneInfo{
   long        numHalftones;
   gxHalftone  halftones[1]; 
};
The numHalftones field specifies how many gxHalftone entries are in the gxFormatHalftoneInfo structure. The halftones field specifies each of them.
Listing 3-13 shows how to store halftone information for a page in a format collection.
Listing 3-13 Storing halftone information in a format collection
OSErr MySetFormatHalftones(gxFormat theFormat,
                        gxFormatHalftoneInfo *theFormatHalftones)
{
   OSErr          err;
   Collection  fmtCollection;

   /*
      Get the format collection, and attempt to delete a
      gxFormatHalftoneTag collection item, in case one exists.
      Then, add a new one.
   */
   fmtCollection = GXGetFormatCollection(theFormat);
   RemoveCollectionItem(fmtCollection,
                   gxFormatHalftoneTag,
                   gxPrintingTagID);
   err = AddCollectionItem(fmtCollection,
                     gxFormatHalftoneTag,
                     gxPrintingTagID,
                     sizeof(gxFormatHalftoneInfo),
                     theFormatHalftones);

   /*
      Since we changed the format object's collection items, we
      must call GXChangedFormat.
   */
   if (err == noErr)
      GXChangedFormat(theFormat);
   return err;
}
To provide halftone information for shape objects drawn with the same ink, you use a halftone synonym. For detailed information on how to use halftone synonyms, see the chapter "Advanced Printing Features" in this book.